/*
 *  Cero Project - Copyright   2006 The Cero Developement Team 
 *  (Michael Laguerre, Camille Roux, Matthieu Segret, Mathieu Sivade) 
 * 
 *  This program is free software; you can redistribute it and/or modify it 
 *  under the terms of the GNU General Public License as published by the Free 
 *  Software Foundation; either version 2 of the License, or (at your option) 
 *  any later version.
 * 
 *  This program is distributed in the hope that it will be useful, but 
 *  WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY 
 *  or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 
 *  for more details.
 */

package org.ceroproject.games;

import java.util.Collection;

/**
 * Represents a game action a player may do anytime.
 * 
 * @author Telem
 */
public interface Action {

	/**
	 * Indicates the name of the action
	 * 
	 * @return the name of the Action
	 */
	String getActionName();

	/**
	 * Executes the Action. Actions are responsibles for getting any parameter
	 * they might need, be it through their constructor or using appropriate
	 * parameters getters.
	 * 
	 * @return whatever the action might want to return
	 */
	void executeAction();

	/**
	 * Indicates the game environment at the moment the action is triggered. It
	 * gives action an opportunity to initalize themselves. If the action cannot
	 * be done (this should be indicated by canAct), then an exception will be
	 * thrown.
	 * 
	 * @param game
	 *            The game concerned by the action
	 * @param from
	 *            The zone where the event started
	 * @param to
	 *            The zone where the event ended
	 * @param selectedCards
	 *            The collection of cards selected when the action occured
	 * @throws ActionException
	 *             if the action cannot be performed with these informations
	 *             only (probablement due to an improper binding)
	 */
	void playerActed(ActionEvent event) throws ActionException;

	/**
	 * Returns whether the action can be done with these parameters
	 * 
	 * @param event
	 *            the action environment
	 * @return true if the action can be performed with this environment, false
	 *         otherwise
	 */
	boolean canAct(ActionEvent event);

	/**
	 * Returns the informations available when the action was launched
	 * 
	 * @return the informations available when the action was launched
	 */
	ActionEvent getEvent();

	// shortcuts !
	Player getPlayer();

	Game getGame();

	Zone getZoneFrom();

	Zone getZoneTo();

	Collection<Card> getCards();

	public String toString();
}
